home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / utilities / powerbase / pbasedoc / mailmerge < prev    next >
Encoding:
Text File  |  1993-06-29  |  9.3 KB  |  217 lines
  1.                 Mail-merging with Impression and Related Matters
  2.                 ================================================
  3.  
  4. Powerbase is capable of performing direct mail-merging with Impression, the
  5. document-processor marketed by Computer Concepts. Performing this task
  6. involves the use of a module called ImpulseII which Computer Concepts have
  7. placed in the public domain to encourage its adoption as a standard means of
  8. transferring data between RISC OS applications. The ImpulseII module is
  9. included in the !System application on the Powerbase distribution disc.
  10.  
  11. How to merge Powerbase data into an Impression document
  12. =======================================================
  13. Although we have called this file 'MailMerge' the process to be described is
  14. more accurately termed "data-merge" since it is by no means limited to
  15. merging names and addresses into letters: any kind of textual data from a
  16. Powerbase application can be merged into any kind of Impression document.
  17.  
  18. Preparing the Impression document
  19. ---------------------------------
  20. It is probably best to create the document without worrying about the merged
  21. data at first, then insert the necessary commands afterwards. 
  22.  
  23. Wherever you want data from a Powerbase record to appear in the document
  24. proceed as folllows:-
  25.  
  26. (1) Place the caret at the point where the data is to be inserted.
  27.  
  28. (2) Click MENU over the frame, go to the 'Misc' submenu and choose 'Merge
  29. command...'. A dialogue box will appear.
  30.  
  31. (3) Type the following:-
  32.  
  33.                 :Powerbase GetField NAME
  34.  
  35. This is on the understanding that your Powerbase record contains a field
  36. whose tag is NAME and that you want the contents of that field inserting
  37. into the Impression document at that point. Note the spaces and the initial
  38. colon. These are essential.
  39.  
  40. (4) Click on 'Set' or type RETURN. You will see "<Merge>" appear in the
  41.     text.
  42.  
  43. (5) Repeat for all the other Powerbase fields to be inserted in the
  44.     document. All take the form :Powerbase GetField <tag>. All the data in a
  45.     given document must come from the same database. It might be easiest if
  46.     you open the required database and arrange the desktop so that you can
  47.     see both the record window and the Impression document. Clicking MENU
  48.     over a field makes its tag appear in the second menu item.
  49.  
  50. (6) Save the the document!
  51.  
  52. When you look at the document there is nothing to distinguish one merge
  53. command from another; they all appear as "<Merge>". To check up on what a
  54. command actually looks like open up the 'Merge command' dialogue box again
  55. and place the caret at the beginning of the merge command, i.e. immediately
  56. before the initial "<". The text of the command will then appear in the
  57. writable icon of the dialogue box.
  58.  
  59. Merging the data
  60. ----------------
  61. (1) Make sure Impression has been "seen" by the filer. Impression doesn't
  62.     need to actually be on the icon-bar at this point but it doesn't matter
  63.     if it is. 
  64.  
  65. (2) Open the Powerbase database.
  66.  
  67. (3) Drop the Impression document on the record window. If Impression isn't
  68.     already running Powerbase will run it for you. Assuming that the
  69.     document isn't loaded already it will be loaded and displayed. Finally
  70.     Powerbase's 'Data merge' dialogue box will appear. (If the document is
  71.     already loaded Impression will print a message informing you of this.
  72.     When you click on 'OK' the 'Data merge' box appears and you should then
  73.     display the Impression document with 'New view'.)
  74.  
  75. (4) The 'Data merge' window has a writable icon in which you may enter a
  76.     search formula (see '!Tutorial' and 'Print'). Clicking on 'Merge' or
  77.     typing RETURN then extracts data from the first matching record and
  78.     inserts it in the specified places in the Impression document. If no
  79.     search formula was entered the merged record will be the first.
  80.  
  81. (5) Buttons are provided for "next", "previous", "first" and "last" record.
  82.     These work just like the corresponding keypad buttons and the Impression
  83.     document displays the merged data in each case.
  84.  
  85. (6) Clicking on 'Print' will print the Impression document in its displayed
  86.     state, i.e. with the currently merged data. If you select the 'Print
  87.     all' switch then click on 'Merge' a whole series of hard copies will be
  88.     produced, one for each matching record.
  89.  
  90. (7) Note that when the mouse pointer is moved over the Impression document
  91.     it changes to a large red and blue cross which means that you cannot
  92.     edit the document. Clicking SELECT over it has no effect; the caret
  93.     doesn't appear. If you click on 'Cancel' in the dialogue box (or close
  94.     it by clicking on its 'Close' icon) the merged data is removed from the
  95.     document and normal editing is restored.
  96.  
  97. Mail-merging with other applications
  98. ====================================
  99. Powerbase is able to mail-merge directly with Impression only because both
  100. programs support Impulse commands. Most other DTP programs and word-
  101. processors do not recognize such commands and mail-merging with them is
  102. usually accomplished via a CSV (comma  separated values) or similar file.
  103. You will need to read the wordprocessor manual to find out precisely what
  104. format the file should have and also the Powerbase documentation on CSV
  105. files. It should be possible to create a file in whatever format is
  106. required.
  107.  
  108. Powerbase as an 'Impulse' server
  109. ================================
  110. The following is a description of the Impulse "methods" understood by
  111. Powerbase, given in the standard format recommended by Computer Concepts.
  112.     
  113. {powerbase Methods:
  114.         GetPathname
  115.         Selection <string>
  116.         ParseQuery <string>
  117.         GetField <tag>
  118.         GetRecord
  119.         PutFile
  120.         ExpandCode <string>
  121.         GetExpanded <string>
  122.  
  123. Descriptions:
  124. GetPathname
  125.  
  126. Specifies an 'object' i.e. a Powerbase database. If Powerbase has the
  127. required database open it replies with the full pathname of the object,
  128. otherwise it returns an error message. Example of use:
  129.  
  130.   :Powerbase.!Elements GetPathname  (returns pathname of !Elements)
  131.  
  132. R6 points to pathname when calling task is decoding reply.
  133.  
  134. Selection <string>
  135.  
  136. Tells Powerbase about a field, or group of fields, in which the caller is
  137. interested. The fields are specified as a list of tags, separated by any
  138. suitable character (e.g. / or ,). The same separator must appear at the very
  139. end of the tag-list.  Powerbase replies with the maximum data-length of the
  140. combined fields in the selection. Example of use:
  141.  
  142.   :Powerbase Selection NAME/SYM/Z/
  143.  
  144. R6 points to a string which gives data-length.
  145.  
  146. ParseQuery <string>
  147.  
  148. Informs Powerbase of the criteria to be used in selecting records to
  149. transmit to the caller.  The parameter is a standard Powerbase search
  150. formula and Powerbase replies with the title which would normally appear
  151. at the head of one of its printed lists. Example of use:
  152.  
  153.   :Powerbase ParseQuery TYPE=T
  154.  
  155. R6 points to returned title.
  156.  
  157. GetField <tag>
  158.  
  159. Requests from Powerbase the data in the specified field of the next record
  160. which matches the preceding ParseQuery command.
  161.  
  162. When Powerbase replies to the GetField command the calling task should
  163. respond with an ImpulseFetchData, specifying the address and length of the
  164. buffer to be used, and then wait for an Impulse_receive event (reason code
  165. &204) before reading the buffer. 
  166.  
  167. GetRecord [<key>]
  168.  
  169. Sent without a key it requests from Powerbase the next record which matches
  170. the preceding ParseQuery command. If the primary key of a record in the
  171. database is appended then Powerbase will return the record corresponding to
  172. that key. The key must be separated from the GetRecord by a space. 
  173.  
  174. The calling task must follow the procedure described above for GetField.
  175. Powerbase will transmit the fields specified in the Selection command, using
  176. the same separator as was used in that command. Receipt of data may be
  177. followed by another GetRecord command, returning the next matching record
  178. and so on, a zero-length response signifying that there are no more
  179. matching records. If using keys to request specific records you should end
  180. by sending *** as a key to tell Powerbase that the dialogue is finished.
  181. This command and the one below operate only on Subfile 0 of the Powerbase
  182. database. 
  183.  
  184. PutRecord
  185.  
  186. Informs Powerbase that the caller wishes to write a record to the current
  187. Powerbase database. It should be sent as message type &200. A Selection
  188. command should have been previously sent to tell Powerbase what fields to
  189. expect and what separator is to be used. Powerbase will then reply with a
  190. GetRecord command (reason code &201) which the caller should acknowledge
  191. with message type &202, specifying the maximum length of the data which will
  192. be sent. Wait for event &203 which is a request by Powerbase for the caller
  193. to transmit the data. The caller should then do so with ImpulseTransmitData,
  194. specifying the buffer address and the length of data being sent. This may be
  195. immediately followed by  another PutRecord.
  196.  
  197. ExpandCode <string>
  198.  
  199. Requests the expanded form of a code used in a field linked to a validation
  200. table. The parameter string consists of the code itself, then a space,
  201. then the name of the validation table with the column number appended.
  202. Example of use:
  203.  
  204.   :Powerbase ExpandCode T Group0              
  205.  
  206. GetExpanded <string>
  207.  
  208. Combines the functions of GetField and ExpandCode, i.e. it requests the
  209. expanded form of the contents of a specified field. The parameter string is
  210. similar to that for ExpandCode, except that the field tag is substituted for
  211. the code. 
  212. Example of use:
  213.  
  214.   :Powerbase GetExpanded GP Group0
  215.  
  216. }
  217.